Documentation‎ > ‎Entries‎ > ‎

    gnocl::text

    A widget for multi line formatted text editing with unlimited undo/redo functionality.

    Synopsis

    gnocl::text [-option value...]

    Screenshot

    Options

    -baseFont

    type: FONT

    Set default font for the text widget.The value passed to the option is a list of attributes in the following format:

    typeface

    size

    attributes: either bold | italic

    In order to set other attributes such as underline and strike through, then use tags.

    -baseColor

    type: color

    Set default colour for the text widget.
    -buffer

    type: string

    The string must specify an alternative textBuffer-id to be displayed in the current gnocl::text widget. The specified textBuffer specified must have been previously created by the gnocl::textBuffer command.
    -data
    type: string (default: "")
    User defined data which can be retrieved via the cget subcommand.
    -onButtonPress

    type: string (default: "")

    Tcl script which is executed if a mouse button is pressed inside the widget. Before evaluation the following percent strings are substituted:

    %w     widget name
    %t       type of event, one of buttonPress, button2Press or button3Press
    %x      mouse pointer x coordinate
    %y      mouse pointer y coordinate
    %b      button number
    %s      state of buttons and modifiers (bitmask)

    -onButtonRelease

    type: string (default: "")

    Tcl script which is executed if a mouse button is released inside the widget. Before evaluation the following percent strings are substituted:

    %w     widget name
    %t       type of event, one of buttonPress, button2Press or button3Press
    %x      mouse pointer x coordinate
    %y      mouse pointer y coordinate
    %b      button number
    %s      state of buttons and modifiers (bitmask) 
    Note: In order to obtain update cursors position etc., use bindings on the ButtonRelease event.
    -onDragData string (default: "")
    Tcl command which is executed if data is draged from this the widget to another. This command must return the data to be draged. Before evaluation the following percent strings are substituted:
    %w    widget name
    %t    time
    %T    type of data
    -onDropData string (default: "")
    Tcl command which is executed if data is dropped on the widget. Before evaluation the following percent strings are substituted:
    %w    widget name
    %d    data
    %l    length of data
    %t    time
    %T    type of data
    %x    x coordinate
    %y    y coordinate
    -onFocusIn
    type: string (default: "")
    Tcl script which is executed prior to the setting the keyboard input focus to the current widget.
    %w   widget name.
    %g   widget glade name.
    %t
       toplevel widow containing the current widget.
    %p
      parent of the current widget.
    -onFocusOut
    type: string (default: "")
    Tcl script which is executed after the keyboard input focus has left the current widget.
    %w   widget name.
    %g   widget glade name.
    %t
       toplevel widow containing the current widget.
    %p
      parent of the current widget.
    -onKeyPress

    type: string (default: "")

    Tcl script which is executed if a key is pressed inside the widget. Before evaluation the following percent strings are substituted: 

    %w     widget name
    %k      keycode
    %K      keycode as symbol
    %a      character
    %s      state of buttons and modifiers (bitmask)
    %g
         glade/builder name
    %e     event type, ie. "key_press_event"
    The %e substitution string is typically used in conjunction with the gnocl::signalStop command to effectively inhibit further execution of the active event. This functionality is particularly valuable when scripts require the validation of keyboard values.
    -onKeyRelease

    type: string (default: "")

    Tcl script which is executed if a key is released inside the widget. Before evaluation the following percent strings are substituted:

    %w     widget name
    %k      keycode
    %K      keycode as symbol
    %a      character
    %s      state of buttons and modifiers (bitmask)
    %g
         glade/builder name
    %e     event type, ie. "key_release_event"

    -onMotion
    type: string (default: "")
    Tcl script which is executed if the mouse pointer moves inside the widget. Before evaluation the following percent strings are substituted:

    %w     widget name
    %x     mouse pointer x coordinate
    %y     mouse pointer y coordinate
    %s     state of buttons and modifiers (bitmask)


    -onShowHelp

    type: string (default: "")
    Tcl script which is executed in the global scope if the "show-help" signal is received, which is normally the case if the user presses F1 or Ctrl-F1. Before evaluation the following percent strings are substituted:

    %w      widget name
    %h       help type: either "whatsThis" or "tooltip"


    -onApplyTag

    type: string (default: "")
    Tcl script which is executed when a valid tag is applied to the contexts of the textbuffer. Before evaluation the following percent strings are substituted:

    %t     name of tag applied
    %c    column from which the tag was applied
    %r    row from which the tag was applied
    %l     line to which the tag was applied
    %o    offset to which the tag was applied 

    -onBeginUserAction
    type: string (default: "")
    Tcl script which is executed when the buffer signals that user input has begun. Before evaluation the following percent strings are substituted:

    %b    value =1.
    As this event occurs only when user action has begun, it always returns the value 1.
    See Also:  -onEndUserAction
    -onDeleteRange
    type: string (default: "")
    Tcl script which is executed when a valid tag is applied to the contexts of the textbuffer. Before evaluation the following percent strings are substituted:

    %r     row from which the text was deleted
    %c     column from which the text was deleted
    %l      line to which the text was deleted
    %o    offset to which the text was deleted
    %t     deleted text

    -onEndUserAction
    type: string (default: "")
    Tcl script which is executed when the buffer signals that user input has ended. Before evaluation the following percent strings are substituted:

    %b    value =1.
    As this event occurs only when user action has begun, it always returns the value 1.
    See Also:  -onBeginUserAction
    -onInsertChildAnchor
    type: string (default: "")
    Tcl script which is executed when a valid tag is applied to the contexts of the textbuffer. Before evaluation the following percent strings are substituted:

    %a      anchor name
    %r      row at which the anchor has been inserted.
    %c      column at which the anchor has been inserted

    -onInsertText
    type: string (default: "")
    Tcl script which is executed when a valid tag is applied to the contexts of the textbuffer. Before evaluation the following percent strings are substituted:

    %t      text inserted
    %r      row at which the text was inserted
    %c      column at which the text was inserted
    %l      length of text inserted

    -onMarkSet
    type: string (default: "")
    Tcl script which is executed when a valid tag is applied to the contexts of the textbuffer. Before evaluation the following percent strings are substituted:

    %n      name of the mark inserted
    %r      row at which the text was inserted
    %c      column at which the text was inserted

    -onMarkDelete
    type: string (default: "")
    Tcl script which is executed when a valid tag is applied to the contexts of the textbuffer. Before evaluation the following percent strings are substituted:

    %n      name of the deleted mark
    -onModified
    type: string (default: "")
    Tcl script which is executed when the buffer signals that the contexts of the text buffer has been modified. Before evaluation the following percent strings are substituted:

    %c    value =1.

    As this event occurs only when the buffer content changes, it always returns the value 1

    -onPopulatePopup
    type: string (default: "")
    Tcl script which is executed prior to the display of the defaut textwidet popup menu allowing the controlling script to add items and submenus to the popup. This command is used in conjunction with the text widget popup command. Before evaluation the following percent strings are substituted:
    %w   widget name
    %g    widget glade name
    -onRemoveTag
    type: string (default: "")
    Tcl script which is executed when a valid tag is applied to the contexts of the textbuffer. Before evaluation the following percent strings are substituted:

    %t    name of tag removed
    %r    row from which the tag removal began
    %c    column from which the tag removal began
    %l    line at which the tag removal ended
    %o   offset at which the tag removal ended
    -onScroll
    type: string (default: "")
    Tcl script which is executed if the text widget is scrolled. Before evaluation the following percent strings are substituted:

    %w     widget name
    %x      mouse pointer x coordinate
    %y      mouse pointer y coordinate
    %X
        mouse pointer x screen coordinate
    %Y     mouse pointer y screen coordinate
    %s
          state of buttons and modifiers (bitmask)
    %d      direction of motion
    %g      widget glade name

    -onQueryTooltip
    type: string (default: "")
    Tcl script which is executed prior to the display of the widget tooltip.

    %w     widget name
    %x      mouse pointer x coordinate
    %y      mouse pointer y coordinate
    %m
        keyboard mode, ie wether the tooltip appeared in response to a keyboard event, 1 = yes.
    %r      text row under mouse pointer.
    %c
         text column unde mouse pointer.

    -scrollbar
    type: ONE OF always, never, automatic (default: automatic)
    When to show scrollbars. If the value is a list of two elements, the first value is for the horizontal scrollbar and the second value for the vertical scrollbar.
    -pixelsInsideWrap
    type: integer
    Pixels between lines after wrap.
    -pixelsBelowLines
    type: integer
    Pixels below lines.
    -pixelsAboveLines
    type: integer
    Pixels above lines.
    -editable
    type: boolean (default: 1)
    Whether the text in the widget is editable.
    -wrapMode
    type: ONE OF none, char or word (default = ??).
    Wrap mode used for the rendering of the cells.
    -justify
    type: ONE OF left, right, center or fill (default = ??).
    Justification of the lines in one cell.
    -leftMargin
    type: integer
    -rightMargin
    type: integer
    -indent integer
    DESCRIPTION TO BE ADDED
    -cursorVisible boolean (default: 1)
    Whether the cursor is visible.
    -hasFocus 1
    This sets the focus to the widget. To unset the focus it must be set to another widet.
    -hasTooltip boolean (default: 1)
    This sets whether the widget is to display tooltips.
    -sensitive boolean (default: 1)
    Whether or not the item is sensitve to user input.
    -visible boolean (default: 1)
    Whether or not the item is visible.
    -name string
    Name of the widget, can be used to set options in an rc file.
    -tooltip string
    Message that appear next to this widget when the mouse pointer is held over it for a short amount of time.

    Description

    A text widget is used to input and show formatted text. Some text commands need an index as parameter. An index can be either a list of the row and the column, both starting at 0, for example "1 7", or a keyword like end, cursor, selectionStart, selectionEnd with an (without space) appended character offset, for example "selectionStart+3". keywords

    Commands

    id class
    Returns the class of the widget, i.e. text.
    id clear
      Clears the text buffer of all content.
    id configure [-option value...]
    Configures the widget. Option may have any of the values accepted on creation of the widget.
    id copy
    Copies all text to the clipboard.
    id cut
    Copies all text to the clipboard and removes it from the widget.
    id delete
    Deletes the widget and the associated tcl command.
    id signalEmit signal
    Causes the widget to emit a signal under programme control. This causes the handling scripts configured to the matching signal to be called.
    id erase startIndex ?endIndex?
    Removes all text between startIndex and endIndex. endIndex defaults to end.
    id get startIndex ?endIndex?
    Returns the text between startIndex and endIndex. endIndex defaults to end.
    id getCursor
    Returns the  position position of the cursor as list of its row and column

    id gotWordEnd
    Move the cursor to the star of the word in which it is occupied.

    id getLength

    Returns the number of characters in the widget.

    id getLineCount

    Returns the number of lines in the current text view.
    id getLineLength index
    Returns the number of characters in the line specified by the given index.
    id getSelectionBounds 
    Returns list containing the limits of the active selection in the form startRow startCol endRow endCol. If there is no selection, then an empty string is returned.
    id insert index text ?-tags taglist?
    Inserts and position index the text text. If taglist is given the text is taged with each element of the list.
    id lorem
    Inserts a paragraph from the typesetters proofing text "Lorem ipsom dolor..." to the end of the contents of the current textbuffer. 
    id paste
    Pastes text from the clipboard at the current cursor position.
    id scrollToMark mark
    Scrolls the widget so that the specified mark is visible.
    id scrollToPosition index [-option value...]
    Scrolls the widget so that the specified index is visible.
    Sub-Command Options
    -align
    type: a list of the horizontal and vertical alignment or one of topLeft, top, topRight, left, center, right, bottomLeft, bottom, or bottomRight
    Specifies where the index shall be shown.
    -margin
    type: 0 lt float lt 1
    Specifies the margin.
    id search string  [-option value...]
    Sub-Command Options
    -tags taglist

      
    List of tags to apply to identified instances of string within the textbuffer.
    Return a list of occurences of the string within the widget textbuffer.
    id select startIndex ?endIndex?
    Select the text between startIndex and endIndex. endIndex defaults to end.
    id set string
    Sets the content of the text buffer to the value contained in string.
    id setCursor index
    Sets the cursor to position index.
    id spawn
    Returns the name of a new gnocl::text widget which shares the same textbuffer as id.
    id undo 
     Perform a single undo function.
    id redo
      Perform a singe redo function.

    Popup Menu Items

    id popup item widgetId
    Add single item to the popup menu. See gnocl::menuItem for more details on creating menu items.
    id popup separator
    Add a horizontal line to the popup menu in order to cluster related commands together.
    id popup subMenu widgetId submenuId
    Attach a submenu to the popupmenu item specified by widgetId.

    Tags

    id tag apply startIndex endIndex -tags taglist
    Applies the list of tags to the specified text range.
    id tag create tagName [-option value...]
    Creates a tag with name tagName and configures it dependent of the options given. The options are the same as with tag configure.
    id tag clear
    Resets the tag table for the specified object. In effect, all tags and their locations will be deleted.
    id tag delete tagName
    Delete tag definition from the textbuffer tag table. All instances of the tag in the textbuffer will be automatically removed.
    id tag get {row col}
    Obtain a list of tags applied to the specified buffer location.
    id tag remove startIndex endIndex -tags taglist
    Removes the list of tags from the specified text range.
    id tag cget tagName [-option value...]
     NOTE:  NOT YET IMPLEMENTED.
    id tag configure tagName [-option value...]
    Configures the existing tag tagName.

    Tag Options

    -background
    type: color
    Background colour of the text.
    -data
    -strikethrough
    type: boolean (default: 0)
    Whether the text is struck through.
    -underline
    type: ONE OF none, single, double,  low or error (default: none.
    How the text should be underlined.
    -wrapMode
    type: ONE OF none, char or word
    Wrap mode used.
    type: string (default: "")

    User defined data which can be retrieved via the cget subcommand.
    -editable
    type: boolean (default: 0)
    Whether the text can be edited.
    -foreground
    type: color
    Foreground colour of the text.
    -font
    type: FONT
    Font of the text.
    -fontFamily
    Font family of the text.
    -fontStyle
    type: ONE OF normal, oblique or italic (default: normal)
    Font style of the text.
    -fontVariant
    type: ONE OF normal or smallCaps (default: normal)
    Font variant of the text.
    -fontWeight
    type: ONE OF ultralight, light, normal, bold, ultrabold or heavy (default: normal)
    Font weight of the text.
    -fontRise
    type: integer (default: 0)
    How many pixels the text should be risen.
    -fontStretch
    type: ONE OF ultraCondensed, extraCondensed, condensed, semiCondensed, normal, semiExpanded, expanded, extraExpanded or ultraExpanded (default: normal)
    Font stretch of the text.
    -fontSize
    type: integer
    Font size of the text.
    -fontScale
    type: float or ONE OF xx-small, x-small, small, medium, large, x-large or xx-large (default: normal)
    Font scale used.
    -onEvent
    type: string (default: "")
    Tcl command which is executed when the buffer signals that a mouse even has occurs in region tagged. Before evaluation the following percent strings are substituted:

    %w     widget name
    %n     tag name
    %t      type of event
    %x     mouse pointer x coordinate
    %y     mouse pointer y coordinate
    %b     button number
    %s     state of buttons and modifiers (bitmask) 

    -invisible
    type: boolean (default: 0)
    Whether the text is invisible.
    -justify
    type: ONE OF left, right, center or fill
    Justification of the lines.
    -paragraph
    type: color
    Set the paragraph background colour of the text.
    -pixelsAboveLines

    type: integer
    Extra number of pixels to display above tagged text.
    -pixelsBelowLines

    type: integer
    Extra number of pixels to display below tagged text.
    -priority

    type: integer or keyword (one of: raise, lower, top or bottom).
    Each tag in a table has a unique priority; setting the priority of one tag shifts the priorities of all the other tags in the table to maintain a unique priority for each tag. Higher priority tags "win" if two tags both set the same text attribute. When adding a tag, it will be assigned the highest priority by default; so normally the precedence of a set of tags is the order in which they were added.
    -size
    type: integer
    Font size in pango units.
    -sizePoints
    type: float
    Point size in points.
    id tag names
    Returns a list of all tags created for use with current text widget buffer.
    id tag remove startIndex endIndex -tags taglist
    Removes the list of tags to the specified text range.

    Example

    set text [gnocl::text -scrollbar always]

    $text tag create bold \
        -fontWeight bold \

        -foreground blue

    $text insert end "This is "

    $text insert end "Gnocl" -tags bold

    $text insert end "!"

    gnocl::window -title "Text" -child $text

    Offset Keywords

    A number of commands and options used by the gnocl::text allow the use of keywords for a more exact positioning of the text view cursor. These are as follows:

    start  

    end

    cursor

    selectionStart

    selectionEnd

    wordStart

    wordEnd

    sentenceStart

    sentenceEnd

    lineStart

    lineEnd


    Comments

    Sections