1 /* 2 * This file is part of gtkD. 3 * 4 * gtkD is free software; you can redistribute it and/or modify 5 * it under the terms of the GNU Lesser General Public License 6 * as published by the Free Software Foundation; either version 3 7 * of the License, or (at your option) any later version, with 8 * some exceptions, please read the COPYING file. 9 * 10 * gtkD is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with gtkD; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA 18 */ 19 20 // generated automatically - do not change 21 // find conversion definition on APILookup.txt 22 // implement new conversion functionalities on the wrap.utils pakage 23 24 25 module gtk.Label; 26 27 private import glib.ConstructionException; 28 private import glib.Str; 29 private import gobject.ObjectG; 30 private import gobject.Signals; 31 private import gtk.Menu; 32 private import gtk.Misc; 33 private import gtk.Widget; 34 private import gtk.c.functions; 35 public import gtk.c.types; 36 public import gtkc.gtktypes; 37 private import pango.PgAttributeList; 38 private import pango.PgLayout; 39 private import std.algorithm; 40 41 42 /** 43 * The #GtkLabel widget displays a small amount of text. As the name 44 * implies, most labels are used to label another widget such as a 45 * #GtkButton, a #GtkMenuItem, or a #GtkComboBox. 46 * 47 * # CSS nodes 48 * 49 * |[<!-- language="plain" --> 50 * label 51 * ├── [selection] 52 * ├── [link] 53 * ┊ 54 * ╰── [link] 55 * ]| 56 * 57 * GtkLabel has a single CSS node with the name label. A wide variety 58 * of style classes may be applied to labels, such as .title, .subtitle, 59 * .dim-label, etc. In the #GtkShortcutsWindow, labels are used wth the 60 * .keycap style class. 61 * 62 * If the label has a selection, it gets a subnode with name selection. 63 * 64 * If the label has links, there is one subnode per link. These subnodes 65 * carry the link or visited state depending on whether they have been 66 * visited. 67 * 68 * # GtkLabel as GtkBuildable 69 * 70 * The GtkLabel implementation of the GtkBuildable interface supports a 71 * custom <attributes> element, which supports any number of <attribute> 72 * elements. The <attribute> element has attributes named “name“, “value“, 73 * “start“ and “end“ and allows you to specify #PangoAttribute values for 74 * this label. 75 * 76 * An example of a UI definition fragment specifying Pango attributes: 77 * |[ 78 * <object class="GtkLabel"> 79 * <attributes> 80 * <attribute name="weight" value="PANGO_WEIGHT_BOLD"/> 81 * <attribute name="background" value="red" start="5" end="10"/> 82 * </attributes> 83 * </object> 84 * ]| 85 * 86 * The start and end attributes specify the range of characters to which the 87 * Pango attribute applies. If start and end are not specified, the attribute is 88 * applied to the whole text. Note that specifying ranges does not make much 89 * sense with translatable attributes. Use markup embedded in the translatable 90 * content instead. 91 * 92 * # Mnemonics 93 * 94 * Labels may contain “mnemonics”. Mnemonics are 95 * underlined characters in the label, used for keyboard navigation. 96 * Mnemonics are created by providing a string with an underscore before 97 * the mnemonic character, such as `"_File"`, to the 98 * functions gtk_label_new_with_mnemonic() or 99 * gtk_label_set_text_with_mnemonic(). 100 * 101 * Mnemonics automatically activate any activatable widget the label is 102 * inside, such as a #GtkButton; if the label is not inside the 103 * mnemonic’s target widget, you have to tell the label about the target 104 * using gtk_label_set_mnemonic_widget(). Here’s a simple example where 105 * the label is inside a button: 106 * 107 * |[<!-- language="C" --> 108 * // Pressing Alt+H will activate this button 109 * button = gtk_button_new (); 110 * label = gtk_label_new_with_mnemonic ("_Hello"); 111 * gtk_container_add (GTK_CONTAINER (button), label); 112 * ]| 113 * 114 * There’s a convenience function to create buttons with a mnemonic label 115 * already inside: 116 * 117 * |[<!-- language="C" --> 118 * // Pressing Alt+H will activate this button 119 * button = gtk_button_new_with_mnemonic ("_Hello"); 120 * ]| 121 * 122 * To create a mnemonic for a widget alongside the label, such as a 123 * #GtkEntry, you have to point the label at the entry with 124 * gtk_label_set_mnemonic_widget(): 125 * 126 * |[<!-- language="C" --> 127 * // Pressing Alt+H will focus the entry 128 * entry = gtk_entry_new (); 129 * label = gtk_label_new_with_mnemonic ("_Hello"); 130 * gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry); 131 * ]| 132 * 133 * # Markup (styled text) 134 * 135 * To make it easy to format text in a label (changing colors, 136 * fonts, etc.), label text can be provided in a simple 137 * [markup format][PangoMarkupFormat]. 138 * 139 * Here’s how to create a label with a small font: 140 * |[<!-- language="C" --> 141 * label = gtk_label_new (NULL); 142 * gtk_label_set_markup (GTK_LABEL (label), "<small>Small text</small>"); 143 * ]| 144 * 145 * (See [complete documentation][PangoMarkupFormat] of available 146 * tags in the Pango manual.) 147 * 148 * The markup passed to gtk_label_set_markup() must be valid; for example, 149 * literal <, > and & characters must be escaped as <, >, and &. 150 * If you pass text obtained from the user, file, or a network to 151 * gtk_label_set_markup(), you’ll want to escape it with 152 * g_markup_escape_text() or g_markup_printf_escaped(). 153 * 154 * Markup strings are just a convenient way to set the #PangoAttrList on 155 * a label; gtk_label_set_attributes() may be a simpler way to set 156 * attributes in some cases. Be careful though; #PangoAttrList tends to 157 * cause internationalization problems, unless you’re applying attributes 158 * to the entire string (i.e. unless you set the range of each attribute 159 * to [0, %G_MAXINT)). The reason is that specifying the start_index and 160 * end_index for a #PangoAttribute requires knowledge of the exact string 161 * being displayed, so translations will cause problems. 162 * 163 * # Selectable labels 164 * 165 * Labels can be made selectable with gtk_label_set_selectable(). 166 * Selectable labels allow the user to copy the label contents to 167 * the clipboard. Only labels that contain useful-to-copy information 168 * — such as error messages — should be made selectable. 169 * 170 * # Text layout # {#label-text-layout} 171 * 172 * A label can contain any number of paragraphs, but will have 173 * performance problems if it contains more than a small number. 174 * Paragraphs are separated by newlines or other paragraph separators 175 * understood by Pango. 176 * 177 * Labels can automatically wrap text if you call 178 * gtk_label_set_line_wrap(). 179 * 180 * gtk_label_set_justify() sets how the lines in a label align 181 * with one another. If you want to set how the label as a whole 182 * aligns in its available space, see the #GtkWidget:halign and 183 * #GtkWidget:valign properties. 184 * 185 * The #GtkLabel:width-chars and #GtkLabel:max-width-chars properties 186 * can be used to control the size allocation of ellipsized or wrapped 187 * labels. For ellipsizing labels, if either is specified (and less 188 * than the actual text size), it is used as the minimum width, and the actual 189 * text size is used as the natural width of the label. For wrapping labels, 190 * width-chars is used as the minimum width, if specified, and max-width-chars 191 * is used as the natural width. Even if max-width-chars specified, wrapping 192 * labels will be rewrapped to use all of the available width. 193 * 194 * Note that the interpretation of #GtkLabel:width-chars and 195 * #GtkLabel:max-width-chars has changed a bit with the introduction of 196 * [width-for-height geometry management.][geometry-management] 197 * 198 * # Links 199 * 200 * Since 2.18, GTK+ supports markup for clickable hyperlinks in addition 201 * to regular Pango markup. The markup for links is borrowed from HTML, 202 * using the `<a>` with “href“ and “title“ attributes. GTK+ renders links 203 * similar to the way they appear in web browsers, with colored, underlined 204 * text. The “title“ attribute is displayed as a tooltip on the link. 205 * 206 * An example looks like this: 207 * 208 * |[<!-- language="C" --> 209 * const gchar *text = 210 * "Go to the" 211 * "<a href=\"http://www.gtk.org title="<i>Our</i> website\">" 212 * "GTK+ website</a> for more..."; 213 * gtk_label_set_markup (label, text); 214 * ]| 215 * 216 * It is possible to implement custom handling for links and their tooltips with 217 * the #GtkLabel::activate-link signal and the gtk_label_get_current_uri() function. 218 */ 219 public class Label : Misc 220 { 221 /** the main Gtk struct */ 222 protected GtkLabel* gtkLabel; 223 224 /** Get the main Gtk struct */ 225 public GtkLabel* getLabelStruct(bool transferOwnership = false) 226 { 227 if (transferOwnership) 228 ownedRef = false; 229 return gtkLabel; 230 } 231 232 /** the main Gtk struct as a void* */ 233 protected override void* getStruct() 234 { 235 return cast(void*)gtkLabel; 236 } 237 238 /** 239 * Sets our main struct and passes it to the parent class. 240 */ 241 public this (GtkLabel* gtkLabel, bool ownedRef = false) 242 { 243 this.gtkLabel = gtkLabel; 244 super(cast(GtkMisc*)gtkLabel, ownedRef); 245 } 246 247 /** 248 * Creates a new GtkLabel, containing the text in str. 249 * If characters in str are preceded by an underscore, they are 250 * underlined. If you need a literal underscore character in a label, use 251 * '__' (two underscores). The first underlined character represents a 252 * keyboard accelerator called a mnemonic. The mnemonic key can be used 253 * to activate another widget, chosen automatically, or explicitly using 254 * setMnemonicWidget(). 255 * 256 * If setMnemonicWidget() is not called, then the first activatable ancestor of the Label 257 * will be chosen as the mnemonic widget. For instance, if the 258 * label is inside a button or menu item, the button or menu item will 259 * automatically become the mnemonic widget and be activated by 260 * the mnemonic. 261 * Params: 262 * str = The text of the label, with an underscore in front of the 263 * mnemonic character 264 * mnemonic = when false uses the literal text passed in without mnemonic 265 * Throws: ConstructionException GTK+ fails to create the object. 266 */ 267 public this (string str, bool mnemonic=true) 268 { 269 GtkLabel* p; 270 271 if ( mnemonic ) 272 { 273 // GtkWidget* gtk_label_new_with_mnemonic (const gchar *str); 274 p = cast(GtkLabel*)gtk_label_new_with_mnemonic(Str.toStringz(str)); 275 } 276 else 277 { 278 // GtkWidget* gtk_label_new (const gchar *str); 279 p = cast(GtkLabel*)gtk_label_new(Str.toStringz(str)); 280 } 281 282 if(p is null) 283 { 284 throw new ConstructionException("null returned by gtk_label_new"); 285 } 286 287 this(p); 288 } 289 290 /** 291 */ 292 293 /** */ 294 public static GType getType() 295 { 296 return gtk_label_get_type(); 297 } 298 299 /** 300 * Gets the angle of rotation for the label. See 301 * gtk_label_set_angle(). 302 * 303 * Returns: the angle of rotation for the label 304 * 305 * Since: 2.6 306 */ 307 public double getAngle() 308 { 309 return gtk_label_get_angle(gtkLabel); 310 } 311 312 /** 313 * Gets the attribute list that was set on the label using 314 * gtk_label_set_attributes(), if any. This function does 315 * not reflect attributes that come from the labels markup 316 * (see gtk_label_set_markup()). If you want to get the 317 * effective attributes for the label, use 318 * pango_layout_get_attribute (gtk_label_get_layout (label)). 319 * 320 * Returns: the attribute list, or %NULL 321 * if none was set. 322 */ 323 public PgAttributeList getAttributes() 324 { 325 auto p = gtk_label_get_attributes(gtkLabel); 326 327 if(p is null) 328 { 329 return null; 330 } 331 332 return ObjectG.getDObject!(PgAttributeList)(cast(PangoAttrList*) p); 333 } 334 335 /** 336 * Returns the URI for the currently active link in the label. 337 * The active link is the one under the mouse pointer or, in a 338 * selectable label, the link in which the text cursor is currently 339 * positioned. 340 * 341 * This function is intended for use in a #GtkLabel::activate-link handler 342 * or for use in a #GtkWidget::query-tooltip handler. 343 * 344 * Returns: the currently active URI. The string is owned by GTK+ and must 345 * not be freed or modified. 346 * 347 * Since: 2.18 348 */ 349 public string getCurrentUri() 350 { 351 return Str.toString(gtk_label_get_current_uri(gtkLabel)); 352 } 353 354 /** 355 * Returns the ellipsizing position of the label. See gtk_label_set_ellipsize(). 356 * 357 * Returns: #PangoEllipsizeMode 358 * 359 * Since: 2.6 360 */ 361 public PangoEllipsizeMode getEllipsize() 362 { 363 return gtk_label_get_ellipsize(gtkLabel); 364 } 365 366 /** 367 * Returns the justification of the label. See gtk_label_set_justify(). 368 * 369 * Returns: #GtkJustification 370 */ 371 public GtkJustification getJustify() 372 { 373 return gtk_label_get_justify(gtkLabel); 374 } 375 376 /** 377 * Fetches the text from a label widget including any embedded 378 * underlines indicating mnemonics and Pango markup. (See 379 * gtk_label_get_text()). 380 * 381 * Returns: the text of the label widget. This string is 382 * owned by the widget and must not be modified or freed. 383 */ 384 public string getLabel() 385 { 386 return Str.toString(gtk_label_get_label(gtkLabel)); 387 } 388 389 /** 390 * Gets the #PangoLayout used to display the label. 391 * The layout is useful to e.g. convert text positions to 392 * pixel positions, in combination with gtk_label_get_layout_offsets(). 393 * The returned layout is owned by the @label so need not be 394 * freed by the caller. The @label is free to recreate its layout at 395 * any time, so it should be considered read-only. 396 * 397 * Returns: the #PangoLayout for this label 398 */ 399 public PgLayout getLayout() 400 { 401 auto p = gtk_label_get_layout(gtkLabel); 402 403 if(p is null) 404 { 405 return null; 406 } 407 408 return ObjectG.getDObject!(PgLayout)(cast(PangoLayout*) p); 409 } 410 411 /** 412 * Obtains the coordinates where the label will draw the #PangoLayout 413 * representing the text in the label; useful to convert mouse events 414 * into coordinates inside the #PangoLayout, e.g. to take some action 415 * if some part of the label is clicked. Of course you will need to 416 * create a #GtkEventBox to receive the events, and pack the label 417 * inside it, since labels are windowless (they return %FALSE from 418 * gtk_widget_get_has_window()). Remember 419 * when using the #PangoLayout functions you need to convert to 420 * and from pixels using PANGO_PIXELS() or #PANGO_SCALE. 421 * 422 * Params: 423 * x = location to store X offset of layout, or %NULL 424 * y = location to store Y offset of layout, or %NULL 425 */ 426 public void getLayoutOffsets(out int x, out int y) 427 { 428 gtk_label_get_layout_offsets(gtkLabel, &x, &y); 429 } 430 431 /** 432 * Returns whether lines in the label are automatically wrapped. 433 * See gtk_label_set_line_wrap(). 434 * 435 * Returns: %TRUE if the lines of the label are automatically wrapped. 436 */ 437 public bool getLineWrap() 438 { 439 return gtk_label_get_line_wrap(gtkLabel) != 0; 440 } 441 442 /** 443 * Returns line wrap mode used by the label. See gtk_label_set_line_wrap_mode(). 444 * 445 * Returns: %TRUE if the lines of the label are automatically wrapped. 446 * 447 * Since: 2.10 448 */ 449 public PangoWrapMode getLineWrapMode() 450 { 451 return gtk_label_get_line_wrap_mode(gtkLabel); 452 } 453 454 /** 455 * Gets the number of lines to which an ellipsized, wrapping 456 * label should be limited. See gtk_label_set_lines(). 457 * 458 * Returns: The number of lines 459 * 460 * Since: 3.10 461 */ 462 public int getLines() 463 { 464 return gtk_label_get_lines(gtkLabel); 465 } 466 467 /** 468 * Retrieves the desired maximum width of @label, in characters. See 469 * gtk_label_set_width_chars(). 470 * 471 * Returns: the maximum width of the label in characters. 472 * 473 * Since: 2.6 474 */ 475 public int getMaxWidthChars() 476 { 477 return gtk_label_get_max_width_chars(gtkLabel); 478 } 479 480 /** 481 * If the label has been set so that it has an mnemonic key this function 482 * returns the keyval used for the mnemonic accelerator. If there is no 483 * mnemonic set up it returns #GDK_KEY_VoidSymbol. 484 * 485 * Returns: GDK keyval usable for accelerators, or #GDK_KEY_VoidSymbol 486 */ 487 public uint getMnemonicKeyval() 488 { 489 return gtk_label_get_mnemonic_keyval(gtkLabel); 490 } 491 492 /** 493 * Retrieves the target of the mnemonic (keyboard shortcut) of this 494 * label. See gtk_label_set_mnemonic_widget(). 495 * 496 * Returns: the target of the label’s mnemonic, 497 * or %NULL if none has been set and the default algorithm will be used. 498 */ 499 public Widget getMnemonicWidget() 500 { 501 auto p = gtk_label_get_mnemonic_widget(gtkLabel); 502 503 if(p is null) 504 { 505 return null; 506 } 507 508 return ObjectG.getDObject!(Widget)(cast(GtkWidget*) p); 509 } 510 511 /** 512 * Gets the value set by gtk_label_set_selectable(). 513 * 514 * Returns: %TRUE if the user can copy text from the label 515 */ 516 public bool getSelectable() 517 { 518 return gtk_label_get_selectable(gtkLabel) != 0; 519 } 520 521 /** 522 * Gets the selected range of characters in the label, returning %TRUE 523 * if there’s a selection. 524 * 525 * Params: 526 * start = return location for start of selection, as a character offset 527 * end = return location for end of selection, as a character offset 528 * 529 * Returns: %TRUE if selection is non-empty 530 */ 531 public bool getSelectionBounds(out int start, out int end) 532 { 533 return gtk_label_get_selection_bounds(gtkLabel, &start, &end) != 0; 534 } 535 536 /** 537 * Returns whether the label is in single line mode. 538 * 539 * Returns: %TRUE when the label is in single line mode. 540 * 541 * Since: 2.6 542 */ 543 public bool getSingleLineMode() 544 { 545 return gtk_label_get_single_line_mode(gtkLabel) != 0; 546 } 547 548 /** 549 * Fetches the text from a label widget, as displayed on the 550 * screen. This does not include any embedded underlines 551 * indicating mnemonics or Pango markup. (See gtk_label_get_label()) 552 * 553 * Returns: the text in the label widget. This is the internal 554 * string used by the label, and must not be modified. 555 */ 556 public string getText() 557 { 558 return Str.toString(gtk_label_get_text(gtkLabel)); 559 } 560 561 /** 562 * Returns whether the label is currently keeping track 563 * of clicked links. 564 * 565 * Returns: %TRUE if clicked links are remembered 566 * 567 * Since: 2.18 568 */ 569 public bool getTrackVisitedLinks() 570 { 571 return gtk_label_get_track_visited_links(gtkLabel) != 0; 572 } 573 574 /** 575 * Returns whether the label’s text is interpreted as marked up with 576 * the [Pango text markup language][PangoMarkupFormat]. 577 * See gtk_label_set_use_markup (). 578 * 579 * Returns: %TRUE if the label’s text will be parsed for markup. 580 */ 581 public bool getUseMarkup() 582 { 583 return gtk_label_get_use_markup(gtkLabel) != 0; 584 } 585 586 /** 587 * Returns whether an embedded underline in the label indicates a 588 * mnemonic. See gtk_label_set_use_underline(). 589 * 590 * Returns: %TRUE whether an embedded underline in the label indicates 591 * the mnemonic accelerator keys. 592 */ 593 public bool getUseUnderline() 594 { 595 return gtk_label_get_use_underline(gtkLabel) != 0; 596 } 597 598 /** 599 * Retrieves the desired width of @label, in characters. See 600 * gtk_label_set_width_chars(). 601 * 602 * Returns: the width of the label in characters. 603 * 604 * Since: 2.6 605 */ 606 public int getWidthChars() 607 { 608 return gtk_label_get_width_chars(gtkLabel); 609 } 610 611 /** 612 * Gets the #GtkLabel:xalign property for @label. 613 * 614 * Returns: the xalign property 615 * 616 * Since: 3.16 617 */ 618 public float getXalign() 619 { 620 return gtk_label_get_xalign(gtkLabel); 621 } 622 623 /** 624 * Gets the #GtkLabel:yalign property for @label. 625 * 626 * Returns: the yalign property 627 * 628 * Since: 3.16 629 */ 630 public float getYalign() 631 { 632 return gtk_label_get_yalign(gtkLabel); 633 } 634 635 /** 636 * Selects a range of characters in the label, if the label is selectable. 637 * See gtk_label_set_selectable(). If the label is not selectable, 638 * this function has no effect. If @start_offset or 639 * @end_offset are -1, then the end of the label will be substituted. 640 * 641 * Params: 642 * startOffset = start offset (in characters not bytes) 643 * endOffset = end offset (in characters not bytes) 644 */ 645 public void selectRegion(int startOffset, int endOffset) 646 { 647 gtk_label_select_region(gtkLabel, startOffset, endOffset); 648 } 649 650 /** 651 * Sets the angle of rotation for the label. An angle of 90 reads from 652 * from bottom to top, an angle of 270, from top to bottom. The angle 653 * setting for the label is ignored if the label is selectable, 654 * wrapped, or ellipsized. 655 * 656 * Params: 657 * angle = the angle that the baseline of the label makes with 658 * the horizontal, in degrees, measured counterclockwise 659 * 660 * Since: 2.6 661 */ 662 public void setAngle(double angle) 663 { 664 gtk_label_set_angle(gtkLabel, angle); 665 } 666 667 /** 668 * Sets a #PangoAttrList; the attributes in the list are applied to the 669 * label text. 670 * 671 * The attributes set with this function will be applied 672 * and merged with any other attributes previously effected by way 673 * of the #GtkLabel:use-underline or #GtkLabel:use-markup properties. 674 * While it is not recommended to mix markup strings with manually set 675 * attributes, if you must; know that the attributes will be applied 676 * to the label after the markup string is parsed. 677 * 678 * Params: 679 * attrs = a #PangoAttrList, or %NULL 680 */ 681 public void setAttributes(PgAttributeList attrs) 682 { 683 gtk_label_set_attributes(gtkLabel, (attrs is null) ? null : attrs.getPgAttributeListStruct()); 684 } 685 686 /** 687 * Sets the mode used to ellipsize (add an ellipsis: "...") to the text 688 * if there is not enough space to render the entire string. 689 * 690 * Params: 691 * mode = a #PangoEllipsizeMode 692 * 693 * Since: 2.6 694 */ 695 public void setEllipsize(PangoEllipsizeMode mode) 696 { 697 gtk_label_set_ellipsize(gtkLabel, mode); 698 } 699 700 /** 701 * Sets the alignment of the lines in the text of the label relative to 702 * each other. %GTK_JUSTIFY_LEFT is the default value when the widget is 703 * first created with gtk_label_new(). If you instead want to set the 704 * alignment of the label as a whole, use gtk_widget_set_halign() instead. 705 * gtk_label_set_justify() has no effect on labels containing only a 706 * single line. 707 * 708 * Params: 709 * jtype = a #GtkJustification 710 */ 711 public void setJustify(GtkJustification jtype) 712 { 713 gtk_label_set_justify(gtkLabel, jtype); 714 } 715 716 /** 717 * Sets the text of the label. The label is interpreted as 718 * including embedded underlines and/or Pango markup depending 719 * on the values of the #GtkLabel:use-underline and 720 * #GtkLabel:use-markup properties. 721 * 722 * Params: 723 * str = the new text to set for the label 724 */ 725 public void setLabel(string str) 726 { 727 gtk_label_set_label(gtkLabel, Str.toStringz(str)); 728 } 729 730 /** 731 * Toggles line wrapping within the #GtkLabel widget. %TRUE makes it break 732 * lines if text exceeds the widget’s size. %FALSE lets the text get cut off 733 * by the edge of the widget if it exceeds the widget size. 734 * 735 * Note that setting line wrapping to %TRUE does not make the label 736 * wrap at its parent container’s width, because GTK+ widgets 737 * conceptually can’t make their requisition depend on the parent 738 * container’s size. For a label that wraps at a specific position, 739 * set the label’s width using gtk_widget_set_size_request(). 740 * 741 * Params: 742 * wrap = the setting 743 */ 744 public void setLineWrap(bool wrap) 745 { 746 gtk_label_set_line_wrap(gtkLabel, wrap); 747 } 748 749 /** 750 * If line wrapping is on (see gtk_label_set_line_wrap()) this controls how 751 * the line wrapping is done. The default is %PANGO_WRAP_WORD which means 752 * wrap on word boundaries. 753 * 754 * Params: 755 * wrapMode = the line wrapping mode 756 * 757 * Since: 2.10 758 */ 759 public void setLineWrapMode(PangoWrapMode wrapMode) 760 { 761 gtk_label_set_line_wrap_mode(gtkLabel, wrapMode); 762 } 763 764 /** 765 * Sets the number of lines to which an ellipsized, wrapping label 766 * should be limited. This has no effect if the label is not wrapping 767 * or ellipsized. Set this to -1 if you don’t want to limit the 768 * number of lines. 769 * 770 * Params: 771 * lines = the desired number of lines, or -1 772 * 773 * Since: 3.10 774 */ 775 public void setLines(int lines) 776 { 777 gtk_label_set_lines(gtkLabel, lines); 778 } 779 780 /** 781 * Parses @str which is marked up with the 782 * [Pango text markup language][PangoMarkupFormat], setting the 783 * label’s text and attribute list based on the parse results. 784 * 785 * If the @str is external data, you may need to escape it with 786 * g_markup_escape_text() or g_markup_printf_escaped(): 787 * 788 * |[<!-- language="C" --> 789 * const char *format = "<span style=\"italic\">\%s</span>"; 790 * char *markup; 791 * 792 * markup = g_markup_printf_escaped (format, str); 793 * gtk_label_set_markup (GTK_LABEL (label), markup); 794 * g_free (markup); 795 * ]| 796 * 797 * This function will set the #GtkLabel:use-markup property to %TRUE as 798 * a side effect. 799 * 800 * If you set the label contents using the #GtkLabel:label property you 801 * should also ensure that you set the #GtkLabel:use-markup property 802 * accordingly. 803 * 804 * See also: gtk_label_set_text() 805 * 806 * Params: 807 * str = a markup string (see [Pango markup format][PangoMarkupFormat]) 808 */ 809 public void setMarkup(string str) 810 { 811 gtk_label_set_markup(gtkLabel, Str.toStringz(str)); 812 } 813 814 /** 815 * Parses @str which is marked up with the 816 * [Pango text markup language][PangoMarkupFormat], 817 * setting the label’s text and attribute list based on the parse results. 818 * If characters in @str are preceded by an underscore, they are underlined 819 * indicating that they represent a keyboard accelerator called a mnemonic. 820 * 821 * The mnemonic key can be used to activate another widget, chosen 822 * automatically, or explicitly using gtk_label_set_mnemonic_widget(). 823 * 824 * Params: 825 * str = a markup string (see 826 * [Pango markup format][PangoMarkupFormat]) 827 */ 828 public void setMarkupWithMnemonic(string str) 829 { 830 gtk_label_set_markup_with_mnemonic(gtkLabel, Str.toStringz(str)); 831 } 832 833 /** 834 * Sets the desired maximum width in characters of @label to @n_chars. 835 * 836 * Params: 837 * nChars = the new desired maximum width, in characters. 838 * 839 * Since: 2.6 840 */ 841 public void setMaxWidthChars(int nChars) 842 { 843 gtk_label_set_max_width_chars(gtkLabel, nChars); 844 } 845 846 /** 847 * If the label has been set so that it has an mnemonic key (using 848 * i.e. gtk_label_set_markup_with_mnemonic(), 849 * gtk_label_set_text_with_mnemonic(), gtk_label_new_with_mnemonic() 850 * or the “use_underline” property) the label can be associated with a 851 * widget that is the target of the mnemonic. When the label is inside 852 * a widget (like a #GtkButton or a #GtkNotebook tab) it is 853 * automatically associated with the correct widget, but sometimes 854 * (i.e. when the target is a #GtkEntry next to the label) you need to 855 * set it explicitly using this function. 856 * 857 * The target widget will be accelerated by emitting the 858 * GtkWidget::mnemonic-activate signal on it. The default handler for 859 * this signal will activate the widget if there are no mnemonic collisions 860 * and toggle focus between the colliding widgets otherwise. 861 * 862 * Params: 863 * widget = the target #GtkWidget, or %NULL to unset 864 */ 865 public void setMnemonicWidget(Widget widget) 866 { 867 gtk_label_set_mnemonic_widget(gtkLabel, (widget is null) ? null : widget.getWidgetStruct()); 868 } 869 870 /** 871 * The pattern of underlines you want under the existing text within the 872 * #GtkLabel widget. For example if the current text of the label says 873 * “FooBarBaz” passing a pattern of “___ ___” will underline 874 * “Foo” and “Baz” but not “Bar”. 875 * 876 * Params: 877 * pattern = The pattern as described above. 878 */ 879 public void setPattern(string pattern) 880 { 881 gtk_label_set_pattern(gtkLabel, Str.toStringz(pattern)); 882 } 883 884 /** 885 * Selectable labels allow the user to select text from the label, for 886 * copy-and-paste. 887 * 888 * Params: 889 * setting = %TRUE to allow selecting text in the label 890 */ 891 public void setSelectable(bool setting) 892 { 893 gtk_label_set_selectable(gtkLabel, setting); 894 } 895 896 /** 897 * Sets whether the label is in single line mode. 898 * 899 * Params: 900 * singleLineMode = %TRUE if the label should be in single line mode 901 * 902 * Since: 2.6 903 */ 904 public void setSingleLineMode(bool singleLineMode) 905 { 906 gtk_label_set_single_line_mode(gtkLabel, singleLineMode); 907 } 908 909 /** 910 * Sets the text within the #GtkLabel widget. It overwrites any text that 911 * was there before. 912 * 913 * This function will clear any previously set mnemonic accelerators, and 914 * set the #GtkLabel:use-underline property to %FALSE as a side effect. 915 * 916 * This function will set the #GtkLabel:use-markup property to %FALSE 917 * as a side effect. 918 * 919 * See also: gtk_label_set_markup() 920 * 921 * Params: 922 * str = The text you want to set 923 */ 924 public void setText(string str) 925 { 926 gtk_label_set_text(gtkLabel, Str.toStringz(str)); 927 } 928 929 /** 930 * Sets the label’s text from the string @str. 931 * If characters in @str are preceded by an underscore, they are underlined 932 * indicating that they represent a keyboard accelerator called a mnemonic. 933 * The mnemonic key can be used to activate another widget, chosen 934 * automatically, or explicitly using gtk_label_set_mnemonic_widget(). 935 * 936 * Params: 937 * str = a string 938 */ 939 public void setTextWithMnemonic(string str) 940 { 941 gtk_label_set_text_with_mnemonic(gtkLabel, Str.toStringz(str)); 942 } 943 944 /** 945 * Sets whether the label should keep track of clicked 946 * links (and use a different color for them). 947 * 948 * Params: 949 * trackLinks = %TRUE to track visited links 950 * 951 * Since: 2.18 952 */ 953 public void setTrackVisitedLinks(bool trackLinks) 954 { 955 gtk_label_set_track_visited_links(gtkLabel, trackLinks); 956 } 957 958 /** 959 * Sets whether the text of the label contains markup in 960 * [Pango’s text markup language][PangoMarkupFormat]. 961 * See gtk_label_set_markup(). 962 * 963 * Params: 964 * setting = %TRUE if the label’s text should be parsed for markup. 965 */ 966 public void setUseMarkup(bool setting) 967 { 968 gtk_label_set_use_markup(gtkLabel, setting); 969 } 970 971 /** 972 * If true, an underline in the text indicates the next character should be 973 * used for the mnemonic accelerator key. 974 * 975 * Params: 976 * setting = %TRUE if underlines in the text indicate mnemonics 977 */ 978 public void setUseUnderline(bool setting) 979 { 980 gtk_label_set_use_underline(gtkLabel, setting); 981 } 982 983 /** 984 * Sets the desired width in characters of @label to @n_chars. 985 * 986 * Params: 987 * nChars = the new desired width, in characters. 988 * 989 * Since: 2.6 990 */ 991 public void setWidthChars(int nChars) 992 { 993 gtk_label_set_width_chars(gtkLabel, nChars); 994 } 995 996 /** 997 * Sets the #GtkLabel:xalign property for @label. 998 * 999 * Params: 1000 * xalign = the new xalign value, between 0 and 1 1001 * 1002 * Since: 3.16 1003 */ 1004 public void setXalign(float xalign) 1005 { 1006 gtk_label_set_xalign(gtkLabel, xalign); 1007 } 1008 1009 /** 1010 * Sets the #GtkLabel:yalign property for @label. 1011 * 1012 * Params: 1013 * yalign = the new yalign value, between 0 and 1 1014 * 1015 * Since: 3.16 1016 */ 1017 public void setYalign(float yalign) 1018 { 1019 gtk_label_set_yalign(gtkLabel, yalign); 1020 } 1021 1022 protected class OnActivateCurrentLinkDelegateWrapper 1023 { 1024 void delegate(Label) dlg; 1025 gulong handlerId; 1026 1027 this(void delegate(Label) dlg) 1028 { 1029 this.dlg = dlg; 1030 onActivateCurrentLinkListeners ~= this; 1031 } 1032 1033 void remove(OnActivateCurrentLinkDelegateWrapper source) 1034 { 1035 foreach(index, wrapper; onActivateCurrentLinkListeners) 1036 { 1037 if (wrapper.handlerId == source.handlerId) 1038 { 1039 onActivateCurrentLinkListeners[index] = null; 1040 onActivateCurrentLinkListeners = std.algorithm.remove(onActivateCurrentLinkListeners, index); 1041 break; 1042 } 1043 } 1044 } 1045 } 1046 OnActivateCurrentLinkDelegateWrapper[] onActivateCurrentLinkListeners; 1047 1048 /** 1049 * A [keybinding signal][GtkBindingSignal] 1050 * which gets emitted when the user activates a link in the label. 1051 * 1052 * Applications may also emit the signal with g_signal_emit_by_name() 1053 * if they need to control activation of URIs programmatically. 1054 * 1055 * The default bindings for this signal are all forms of the Enter key. 1056 * 1057 * Since: 2.18 1058 */ 1059 gulong addOnActivateCurrentLink(void delegate(Label) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 1060 { 1061 auto wrapper = new OnActivateCurrentLinkDelegateWrapper(dlg); 1062 wrapper.handlerId = Signals.connectData( 1063 this, 1064 "activate-current-link", 1065 cast(GCallback)&callBackActivateCurrentLink, 1066 cast(void*)wrapper, 1067 cast(GClosureNotify)&callBackActivateCurrentLinkDestroy, 1068 connectFlags); 1069 return wrapper.handlerId; 1070 } 1071 1072 extern(C) static void callBackActivateCurrentLink(GtkLabel* labelStruct, OnActivateCurrentLinkDelegateWrapper wrapper) 1073 { 1074 wrapper.dlg(wrapper.outer); 1075 } 1076 1077 extern(C) static void callBackActivateCurrentLinkDestroy(OnActivateCurrentLinkDelegateWrapper wrapper, GClosure* closure) 1078 { 1079 wrapper.remove(wrapper); 1080 } 1081 1082 protected class OnActivateLinkDelegateWrapper 1083 { 1084 bool delegate(string, Label) dlg; 1085 gulong handlerId; 1086 1087 this(bool delegate(string, Label) dlg) 1088 { 1089 this.dlg = dlg; 1090 onActivateLinkListeners ~= this; 1091 } 1092 1093 void remove(OnActivateLinkDelegateWrapper source) 1094 { 1095 foreach(index, wrapper; onActivateLinkListeners) 1096 { 1097 if (wrapper.handlerId == source.handlerId) 1098 { 1099 onActivateLinkListeners[index] = null; 1100 onActivateLinkListeners = std.algorithm.remove(onActivateLinkListeners, index); 1101 break; 1102 } 1103 } 1104 } 1105 } 1106 OnActivateLinkDelegateWrapper[] onActivateLinkListeners; 1107 1108 /** 1109 * The signal which gets emitted to activate a URI. 1110 * Applications may connect to it to override the default behaviour, 1111 * which is to call gtk_show_uri_on_window(). 1112 * 1113 * Params: 1114 * uri = the URI that is activated 1115 * 1116 * Returns: %TRUE if the link has been activated 1117 * 1118 * Since: 2.18 1119 */ 1120 gulong addOnActivateLink(bool delegate(string, Label) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 1121 { 1122 auto wrapper = new OnActivateLinkDelegateWrapper(dlg); 1123 wrapper.handlerId = Signals.connectData( 1124 this, 1125 "activate-link", 1126 cast(GCallback)&callBackActivateLink, 1127 cast(void*)wrapper, 1128 cast(GClosureNotify)&callBackActivateLinkDestroy, 1129 connectFlags); 1130 return wrapper.handlerId; 1131 } 1132 1133 extern(C) static int callBackActivateLink(GtkLabel* labelStruct, char* uri, OnActivateLinkDelegateWrapper wrapper) 1134 { 1135 return wrapper.dlg(Str.toString(uri), wrapper.outer); 1136 } 1137 1138 extern(C) static void callBackActivateLinkDestroy(OnActivateLinkDelegateWrapper wrapper, GClosure* closure) 1139 { 1140 wrapper.remove(wrapper); 1141 } 1142 1143 protected class OnCopyClipboardDelegateWrapper 1144 { 1145 void delegate(Label) dlg; 1146 gulong handlerId; 1147 1148 this(void delegate(Label) dlg) 1149 { 1150 this.dlg = dlg; 1151 onCopyClipboardListeners ~= this; 1152 } 1153 1154 void remove(OnCopyClipboardDelegateWrapper source) 1155 { 1156 foreach(index, wrapper; onCopyClipboardListeners) 1157 { 1158 if (wrapper.handlerId == source.handlerId) 1159 { 1160 onCopyClipboardListeners[index] = null; 1161 onCopyClipboardListeners = std.algorithm.remove(onCopyClipboardListeners, index); 1162 break; 1163 } 1164 } 1165 } 1166 } 1167 OnCopyClipboardDelegateWrapper[] onCopyClipboardListeners; 1168 1169 /** 1170 * The ::copy-clipboard signal is a 1171 * [keybinding signal][GtkBindingSignal] 1172 * which gets emitted to copy the selection to the clipboard. 1173 * 1174 * The default binding for this signal is Ctrl-c. 1175 */ 1176 gulong addOnCopyClipboard(void delegate(Label) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 1177 { 1178 auto wrapper = new OnCopyClipboardDelegateWrapper(dlg); 1179 wrapper.handlerId = Signals.connectData( 1180 this, 1181 "copy-clipboard", 1182 cast(GCallback)&callBackCopyClipboard, 1183 cast(void*)wrapper, 1184 cast(GClosureNotify)&callBackCopyClipboardDestroy, 1185 connectFlags); 1186 return wrapper.handlerId; 1187 } 1188 1189 extern(C) static void callBackCopyClipboard(GtkLabel* labelStruct, OnCopyClipboardDelegateWrapper wrapper) 1190 { 1191 wrapper.dlg(wrapper.outer); 1192 } 1193 1194 extern(C) static void callBackCopyClipboardDestroy(OnCopyClipboardDelegateWrapper wrapper, GClosure* closure) 1195 { 1196 wrapper.remove(wrapper); 1197 } 1198 1199 protected class OnMoveCursorDelegateWrapper 1200 { 1201 void delegate(GtkMovementStep, int, bool, Label) dlg; 1202 gulong handlerId; 1203 1204 this(void delegate(GtkMovementStep, int, bool, Label) dlg) 1205 { 1206 this.dlg = dlg; 1207 onMoveCursorListeners ~= this; 1208 } 1209 1210 void remove(OnMoveCursorDelegateWrapper source) 1211 { 1212 foreach(index, wrapper; onMoveCursorListeners) 1213 { 1214 if (wrapper.handlerId == source.handlerId) 1215 { 1216 onMoveCursorListeners[index] = null; 1217 onMoveCursorListeners = std.algorithm.remove(onMoveCursorListeners, index); 1218 break; 1219 } 1220 } 1221 } 1222 } 1223 OnMoveCursorDelegateWrapper[] onMoveCursorListeners; 1224 1225 /** 1226 * The ::move-cursor signal is a 1227 * [keybinding signal][GtkBindingSignal] 1228 * which gets emitted when the user initiates a cursor movement. 1229 * If the cursor is not visible in @entry, this signal causes 1230 * the viewport to be moved instead. 1231 * 1232 * Applications should not connect to it, but may emit it with 1233 * g_signal_emit_by_name() if they need to control the cursor 1234 * programmatically. 1235 * 1236 * The default bindings for this signal come in two variants, 1237 * the variant with the Shift modifier extends the selection, 1238 * the variant without the Shift modifer does not. 1239 * There are too many key combinations to list them all here. 1240 * - Arrow keys move by individual characters/lines 1241 * - Ctrl-arrow key combinations move by words/paragraphs 1242 * - Home/End keys move to the ends of the buffer 1243 * 1244 * Params: 1245 * step = the granularity of the move, as a #GtkMovementStep 1246 * count = the number of @step units to move 1247 * extendSelection = %TRUE if the move should extend the selection 1248 */ 1249 gulong addOnMoveCursor(void delegate(GtkMovementStep, int, bool, Label) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 1250 { 1251 auto wrapper = new OnMoveCursorDelegateWrapper(dlg); 1252 wrapper.handlerId = Signals.connectData( 1253 this, 1254 "move-cursor", 1255 cast(GCallback)&callBackMoveCursor, 1256 cast(void*)wrapper, 1257 cast(GClosureNotify)&callBackMoveCursorDestroy, 1258 connectFlags); 1259 return wrapper.handlerId; 1260 } 1261 1262 extern(C) static void callBackMoveCursor(GtkLabel* labelStruct, GtkMovementStep step, int count, bool extendSelection, OnMoveCursorDelegateWrapper wrapper) 1263 { 1264 wrapper.dlg(step, count, extendSelection, wrapper.outer); 1265 } 1266 1267 extern(C) static void callBackMoveCursorDestroy(OnMoveCursorDelegateWrapper wrapper, GClosure* closure) 1268 { 1269 wrapper.remove(wrapper); 1270 } 1271 1272 protected class OnPopulatePopupDelegateWrapper 1273 { 1274 void delegate(Menu, Label) dlg; 1275 gulong handlerId; 1276 1277 this(void delegate(Menu, Label) dlg) 1278 { 1279 this.dlg = dlg; 1280 onPopulatePopupListeners ~= this; 1281 } 1282 1283 void remove(OnPopulatePopupDelegateWrapper source) 1284 { 1285 foreach(index, wrapper; onPopulatePopupListeners) 1286 { 1287 if (wrapper.handlerId == source.handlerId) 1288 { 1289 onPopulatePopupListeners[index] = null; 1290 onPopulatePopupListeners = std.algorithm.remove(onPopulatePopupListeners, index); 1291 break; 1292 } 1293 } 1294 } 1295 } 1296 OnPopulatePopupDelegateWrapper[] onPopulatePopupListeners; 1297 1298 /** 1299 * The ::populate-popup signal gets emitted before showing the 1300 * context menu of the label. Note that only selectable labels 1301 * have context menus. 1302 * 1303 * If you need to add items to the context menu, connect 1304 * to this signal and append your menuitems to the @menu. 1305 * 1306 * Params: 1307 * menu = the menu that is being populated 1308 */ 1309 gulong addOnPopulatePopup(void delegate(Menu, Label) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 1310 { 1311 auto wrapper = new OnPopulatePopupDelegateWrapper(dlg); 1312 wrapper.handlerId = Signals.connectData( 1313 this, 1314 "populate-popup", 1315 cast(GCallback)&callBackPopulatePopup, 1316 cast(void*)wrapper, 1317 cast(GClosureNotify)&callBackPopulatePopupDestroy, 1318 connectFlags); 1319 return wrapper.handlerId; 1320 } 1321 1322 extern(C) static void callBackPopulatePopup(GtkLabel* labelStruct, GtkMenu* menu, OnPopulatePopupDelegateWrapper wrapper) 1323 { 1324 wrapper.dlg(ObjectG.getDObject!(Menu)(menu), wrapper.outer); 1325 } 1326 1327 extern(C) static void callBackPopulatePopupDestroy(OnPopulatePopupDelegateWrapper wrapper, GClosure* closure) 1328 { 1329 wrapper.remove(wrapper); 1330 } 1331 }