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 widget.
-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