1 2@c %start of fragment 3 4@deftp Class <gtk-entry> 5Derives from @code{<gtk-editable>}, @code{<gtk-cell-editable>}, 6@code{<gtk-widget>}. 7 8This class defines the following slots: 9 10@table @code 11@item cursor-position 12The current position of the insertion cursor in chars 13 14@item selection-bound 15The position of the opposite end of the selection from the cursor in chars 16 17@item editable 18Whether the entry contents can be edited 19 20@item max-length 21Maximum number of characters for this entry. Zero if no maximum 22 23@item visibility 24FALSE displays the "invisible char" instead of the actual text (password mode) 25 26@item has-frame 27FALSE removes outside bevel from entry 28 29@item inner-border 30Border between text and frame. Overrides the inner-border style property 31 32@item invisible-char 33The character to use when masking entry contents (in "password mode") 34 35@item activates-default 36Whether to activate the default widget (such as the default button in a dialog) 37when Enter is pressed 38 39@item width-chars 40Number of characters to leave space for in the entry 41 42@item scroll-offset 43Number of pixels of the entry scrolled off the screen to the left 44 45@item text 46The contents of the entry 47 48@item xalign 49The horizontal alignment, from 0 (left) to 1 (right). Reversed for RTL layouts. 50 51@item truncate-multiline 52Whether to truncate multiline pastes to one line. 53 54@item shadow-type 55Which kind of shadow to draw around the entry when has-frame is set 56 57@end table 58 59@end deftp 60 61@defop Signal <gtk-entry> move-cursor (arg0@tie{}@code{<gtk-movement-step>}) (arg1@tie{}@code{<gint>}) (arg2@tie{}@code{<gboolean>}) 62@end defop 63 64@defop Signal <gtk-entry> copy-clipboard 65@end defop 66 67@defop Signal <gtk-entry> populate-popup (arg0@tie{}@code{<gtk-menu>}) 68@end defop 69 70@defop Signal <gtk-entry> activate 71@end defop 72 73@defop Signal <gtk-entry> insert-at-cursor (arg0@tie{}@code{<gchararray>}) 74@end defop 75 76@defop Signal <gtk-entry> delete-from-cursor (arg0@tie{}@code{<gtk-delete-type>}) (arg1@tie{}@code{<gint>}) 77@end defop 78 79@defop Signal <gtk-entry> backspace 80@end defop 81 82@defop Signal <gtk-entry> cut-clipboard 83@end defop 84 85@defop Signal <gtk-entry> paste-clipboard 86@end defop 87 88@defop Signal <gtk-entry> toggle-overwrite 89@end defop 90 91@deffn Function gtk-entry-set-text (self@tie{}@code{<gtk-entry>}) (text@tie{}@code{mchars}) 92@deffnx Method set-text 93Sets the text in the widget to the given value, replacing the current contents. 94 95@table @var 96@item entry 97a @code{<gtk-entry>}. 98 99@item text 100the new text. 101 102@end table 103 104@end deffn 105 106@deffn Function gtk-entry-get-text (self@tie{}@code{<gtk-entry>}) @result{}@tie{} (ret@tie{}@code{mchars}) 107@deffnx Method get-text 108Retrieves the contents of the entry widget. See also 109@code{gtk-editable-get-chars}. 110 111@table @var 112@item entry 113a @code{<gtk-entry>} 114 115@item ret 116a pointer to the contents of the widget as a string. This string points to 117internally allocated storage in the widget and must not be freed, modified or 118stored. 119 120@end table 121 122@end deffn 123 124@deffn Function gtk-entry-set-visibility (self@tie{}@code{<gtk-entry>}) (visible@tie{}@code{bool}) 125@deffnx Method set-visibility 126Sets whether the contents of the entry are visible or not. When visibility is 127set to @samp{@code{#f}}, characters are displayed as the invisible char, and 128will also appear that way when the text in the entry widget is copied elsewhere. 129 130The default invisible char is the asterisk '*', but it can be changed with 131@code{gtk-entry-set-invisible-char}. 132 133@table @var 134@item entry 135a @code{<gtk-entry>}. 136 137@item visible 138@samp{@code{#t}} if the contents of the entry are displayed as plaintext. 139 140@end table 141 142@end deffn 143 144@deffn Function gtk-entry-set-invisible-char (self@tie{}@code{<gtk-entry>}) (ch@tie{}@code{unsigned-int32}) 145@deffnx Method set-invisible-char 146Sets the character to use in place of the actual text when 147@code{gtk-entry-set-visibility} has been called to set text visibility to 148@samp{@code{#f}}. i.e. this is the character used in "password mode" to show the 149user how many characters have been typed. The default invisible char is an 150asterisk ('*'). If you set the invisible char to 0, then the user will get no 151feedback at all; there will be no text on the screen as they type. 152 153@table @var 154@item entry 155a @code{<gtk-entry>} 156 157@item ch 158a Unicode character 159 160@end table 161 162@end deffn 163 164@deffn Function gtk-entry-set-max-length (self@tie{}@code{<gtk-entry>}) (max@tie{}@code{int}) 165@deffnx Method set-max-length 166Sets the maximum allowed length of the contents of the widget. If the current 167contents are longer than the given length, then they will be truncated to fit. 168 169@table @var 170@item entry 171a @code{<gtk-entry>}. 172 173@item max 174the maximum length of the entry, or 0 for no maximum. (other than the maximum 175length of entries.) The value passed in will be clamped to the range 0-65536. 176 177@end table 178 179@end deffn 180 181@deffn Function gtk-entry-get-activates-default (self@tie{}@code{<gtk-entry>}) @result{}@tie{} (ret@tie{}@code{bool}) 182@deffnx Method get-activates-default 183Retrieves the value set by @code{gtk-entry-set-activates-default}. 184 185@table @var 186@item entry 187a @code{<gtk-entry>} 188 189@item ret 190@samp{@code{#t}} if the entry will activate the default widget 191 192@end table 193 194@end deffn 195 196@deffn Function gtk-entry-get-has-frame (self@tie{}@code{<gtk-entry>}) @result{}@tie{} (ret@tie{}@code{bool}) 197@deffnx Method get-has-frame 198Gets the value set by @code{gtk-entry-set-has-frame}. 199 200@table @var 201@item entry 202a @code{<gtk-entry>} 203 204@item ret 205whether the entry has a beveled frame 206 207@end table 208 209@end deffn 210 211@deffn Function gtk-entry-get-inner-border (self@tie{}@code{<gtk-entry>}) @result{}@tie{} (ret@tie{}@code{<gtk-border>}) 212@deffnx Method get-inner-border 213This function returns the entry's inner-border property. See 214@code{gtk-entry-set-inner-border} for more information. 215 216@table @var 217@item entry 218a @code{<gtk-entry>} 219 220@item ret 221the entry's @code{<gtk-border>}, or @samp{@code{#f}} if none was set. 222 223@end table 224 225Since 2.10 226 227@end deffn 228 229@deffn Function gtk-entry-get-width-chars (self@tie{}@code{<gtk-entry>}) @result{}@tie{} (ret@tie{}@code{int}) 230@deffnx Method get-width-chars 231Gets the value set by @code{gtk-entry-set-width-chars}. 232 233@table @var 234@item entry 235a @code{<gtk-entry>} 236 237@item ret 238number of chars to request space for, or negative if unset 239 240@end table 241 242@end deffn 243 244@deffn Function gtk-entry-set-activates-default (self@tie{}@code{<gtk-entry>}) (setting@tie{}@code{bool}) 245@deffnx Method set-activates-default 246If @var{setting} is @samp{@code{#t}}, pressing Enter in the @var{entry} will 247activate the default widget for the window containing the entry. This usually 248means that the dialog box containing the entry will be closed, since the default 249widget is usually one of the dialog buttons. 250 251(For experts: if @var{setting} is @samp{@code{#t}}, the entry calls 252@code{gtk-window-activate-default} on the window containing the entry, in the 253default handler for the "activate" signal.) 254 255@table @var 256@item entry 257a @code{<gtk-entry>} 258 259@item setting 260@samp{@code{#t}} to activate window's default widget on Enter keypress 261 262@end table 263 264@end deffn 265 266@deffn Function gtk-entry-set-has-frame (self@tie{}@code{<gtk-entry>}) (setting@tie{}@code{bool}) 267@deffnx Method set-has-frame 268Sets whether the entry has a beveled frame around it. 269 270@table @var 271@item entry 272a @code{<gtk-entry>} 273 274@item setting 275new value 276 277@end table 278 279@end deffn 280 281@deffn Function gtk-entry-set-inner-border (self@tie{}@code{<gtk-entry>}) (border@tie{}@code{<gtk-border>}) 282@deffnx Method set-inner-border 283Sets @samp{entry}'s inner-border property to @samp{border}, or clears it if 284@samp{@code{#f}} is passed. The inner-border is the area around the entry's 285text, but inside its frame. 286 287If set, this property overrides the inner-border style property. Overriding the 288style-provided border is useful when you want to do in-place editing of some 289text in a canvas or list widget, where pixel-exact positioning of the entry is 290important. 291 292@table @var 293@item entry 294a @code{<gtk-entry>} 295 296@item border 297a @code{<gtk-border>}, or @samp{@code{#f}} 298 299@end table 300 301Since 2.10 302 303@end deffn 304 305@deffn Function gtk-entry-set-width-chars (self@tie{}@code{<gtk-entry>}) (n_chars@tie{}@code{int}) 306@deffnx Method set-width-chars 307Changes the size request of the entry to be about the right size for 308@var{n-chars} characters. Note that it changes the size @emph{request}, the size 309can still be affected by how you pack the widget into containers. If 310@var{n-chars} is -1, the size reverts to the default entry size. 311 312@table @var 313@item entry 314a @code{<gtk-entry>} 315 316@item n-chars 317width in chars 318 319@end table 320 321@end deffn 322 323@deffn Function gtk-entry-get-invisible-char (self@tie{}@code{<gtk-entry>}) @result{}@tie{} (ret@tie{}@code{unsigned-int32}) 324@deffnx Method get-invisible-char 325Retrieves the character displayed in place of the real characters for entries 326with visisbility set to false. See @code{gtk-entry-set-invisible-char}. 327 328@table @var 329@item entry 330a @code{<gtk-entry>} 331 332@item ret 333the current invisible char, or 0, if the entry does not show invisible text at 334all. 335 336@end table 337 338@end deffn 339 340@deffn Function gtk-entry-set-alignment (self@tie{}@code{<gtk-entry>}) (xalign@tie{}@code{float}) 341@deffnx Method set-alignment 342Sets the alignment for the contents of the entry. This controls the horizontal 343positioning of the contents when the displayed text is shorter than the width of 344the entry. 345 346@table @var 347@item entry 348a @code{<gtk-entry>} 349 350@item xalign 351The horizontal alignment, from 0 (left) to 1 (right). Reversed for RTL layouts 352 353@end table 354 355Since 2.4 356 357@end deffn 358 359@deffn Function gtk-entry-get-alignment (self@tie{}@code{<gtk-entry>}) @result{}@tie{} (ret@tie{}@code{float}) 360@deffnx Method get-alignment 361Gets the value set by @code{gtk-entry-set-alignment}. 362 363@table @var 364@item entry 365a @code{<gtk-entry>} 366 367@item ret 368the alignment 369 370@end table 371 372Since 2.4 373 374@end deffn 375 376@deffn Function gtk-entry-get-layout (self@tie{}@code{<gtk-entry>}) @result{}@tie{} (ret@tie{}@code{<pango-layout>}) 377@deffnx Method get-layout 378Gets the @code{<pango-layout>} used to display the entry. The layout is useful 379to e.g. convert text positions to pixel positions, in combination with 380@code{gtk-entry-get-layout-offsets}. The returned layout is owned by the entry 381and must not be modified or freed by the caller. 382 383Keep in mind that the layout text may contain a preedit string, so 384@code{gtk-entry-layout-index-to-text-index} and 385@code{gtk-entry-text-index-to-layout-index} are needed to convert byte indices 386in the layout to byte indices in the entry contents. 387 388@table @var 389@item entry 390a @code{<gtk-entry>} 391 392@item ret 393the @code{<pango-layout>} for this entry 394 395@end table 396 397@end deffn 398 399@deffn Function gtk-entry-get-layout-offsets (self@tie{}@code{<gtk-entry>}) @result{}@tie{} (x@tie{}@code{int}) (y@tie{}@code{int}) 400@deffnx Method get-layout-offsets 401Obtains the position of the @code{<pango-layout>} used to render text in the 402entry, in widget coordinates. Useful if you want to line up the text in an entry 403with some other text, e.g. when using the entry to implement editable cells in a 404sheet widget. 405 406Also useful to convert mouse events into coordinates inside the 407@code{<pango-layout>}, e.g. to take some action if some part of the entry text 408is clicked. 409 410Note that as the user scrolls around in the entry the offsets will change; 411you'll need to connect to the "notify::scroll-offset" signal to track this. 412Remember when using the @code{<pango-layout>} functions you need to convert to 413and from pixels using @code{pango-pixels} or @code{<pango-scale>}. 414 415Keep in mind that the layout text may contain a preedit string, so 416@code{gtk-entry-layout-index-to-text-index} and 417@code{gtk-entry-text-index-to-layout-index} are needed to convert byte indices 418in the layout to byte indices in the entry contents. 419 420@table @var 421@item entry 422a @code{<gtk-entry>} 423 424@item x 425location to store X offset of layout, or @samp{@code{#f}} 426 427@item y 428location to store Y offset of layout, or @samp{@code{#f}} 429 430@end table 431 432@end deffn 433 434@deffn Function gtk-entry-get-max-length (self@tie{}@code{<gtk-entry>}) @result{}@tie{} (ret@tie{}@code{int}) 435@deffnx Method get-max-length 436Retrieves the maximum allowed length of the text in @var{entry}. See 437@code{gtk-entry-set-max-length}. 438 439@table @var 440@item entry 441a @code{<gtk-entry>} 442 443@item ret 444the maximum allowed number of characters in @code{<gtk-entry>}, or 0 if there is 445no maximum. 446 447@end table 448 449@end deffn 450 451@deffn Function gtk-entry-get-visibility (self@tie{}@code{<gtk-entry>}) @result{}@tie{} (ret@tie{}@code{bool}) 452@deffnx Method get-visibility 453Retrieves whether the text in @var{entry} is visible. See 454@code{gtk-entry-set-visibility}. 455 456@table @var 457@item entry 458a @code{<gtk-entry>} 459 460@item ret 461@samp{@code{#t}} if the text is currently visible 462 463@end table 464 465@end deffn 466 467@deffn Function gtk-entry-set-completion (self@tie{}@code{<gtk-entry>}) (completion@tie{}@code{<gtk-entry-completion>}) 468@deffnx Method set-completion 469Sets @var{completion} to be the auxiliary completion object to use with 470@var{entry}. All further configuration of the completion mechanism is done on 471@var{completion} using the @code{<gtk-entry-completion>} API. Completion is 472disabled if @var{completion} is set to @samp{@code{#f}}. 473 474@table @var 475@item entry 476A @code{<gtk-entry>}. 477 478@item completion 479The @code{<gtk-entry-completion>} or @samp{@code{#f}}. 480 481@end table 482 483Since 2.4 484 485@end deffn 486 487@deffn Function gtk-entry-get-completion (self@tie{}@code{<gtk-entry>}) @result{}@tie{} (ret@tie{}@code{<gtk-entry-completion>}) 488@deffnx Method get-completion 489Returns the auxiliary completion object currently in use by @var{entry}. 490 491@table @var 492@item entry 493A @code{<gtk-entry>}. 494 495@item ret 496The auxiliary completion object currently in use by @var{entry}. 497 498@end table 499 500Since 2.4 501 502@end deffn 503 504 505@c %end of fragment 506