1.62 class fragment

A fragment object describes part of a text_buffer object. Fragments are maintained by the text_buffer they are associated with and move along with edit operations, so they keep pointing to the same text.

Fragments have been implemented to allow for annotation of textual information. Besides defining a range of characters, fragments define their visual appearance when displayed by an editor. The location of fragments in a text can be visualised by a text_margin object associated with an editor object. This visualisation is done using icons (image objects).

Fragments may be used to realise multiple fonts, styles and colours in editor objects. Another use for fragments is to make fragments of the text active, e.g. allow the user to follow a link from the specified fragment (hyper-text). Finally, fragments may be used as text-markers.

The following fragment turns the selection of an editor into bold font:

demo :-
        send(new(V, view), open),
        send(V, style, bold, style(bold := @on)),
        send(V, key_binding, '\C-b',
                 message(@prolog, make_bold, V?editor)).

make_bold(E) :-
        get(E, selection_start, Start),
        get(E, selection_end, End),
        Len is End - Start,
        new(_, fragment(E, Start, Len, bold)).

See also

- editor-selected_fragment
- editor-margin
- class style
- editor-selected_fragment_style
- editor-styles
- editor->selected_fragment
- text_buffer<-find_all_fragments
- class font
- class editor
- class text_buffer
- class text_margin

1.62.1 Instance variables

fragment-previous: fragment*

Previous in double-linked chain.

fragment-next: fragment*

These variables together with text_buffer<-first_fragment and text_buffer<-last_fragment define the double linked list of fragments that is sorted on fragment<-start.

These methods are normally not used to analyse the available fragments. See text_buffer<-find_all_fragments and text_buffer<-find_fragment for locating fragments.

fragment <- style: [name]

Logical name of the fragment. This logical name expresses the semantics of the text inside it (title, example, ...). Using editor->style the user specifies how fragments of this style are visualised.

See also

text_margin-styles

1.62.2 Send methods

fragment ->end: int

Inherits description from: fragment<-end

fragment ->does_include: what={start,end}

Test whether start or end is included.

fragment ->include: what=[{start,end,both}], include=[bool]

Define whether start and end are included. If text insertion takes place exactly on the corresponding end of the fragment, the fragment is expanded if include equals @on or left untouched if include equals @off.

What defaults to both (include both start and end). include defaults to @on. Initially neither of the ends is included. See also fragment->insert.

fragment ->initialise: text=text_buffer, start=int, length=int, style=[name]

Create a fragment on the specified text_buffer object. The fragment starts are fragment<-start and is fragment<-length (may be 0) characters long. fragment<-style is a logical indicating the category of the fragment (e.g. title, example, glossary, refers_to, ...). The visual implication of a style-name is determined using editor->style and/or list_browser->style.

fragment ->insert: [int], char_array

Insert text in the fragment. The fragment actually invokes‘text_buffer fragment->insert’with the properly translated arguments. If the index is @default, the text is appended to the fragment. For example, the PceEmacs shell mode uses a fragment to insert the output of the sub-process. See xpce/prolog/lib/emacs/shell_mode.pl.

fragment ->overlap: int|fragment|point

Succeed if the fragment overlaps the specified index, overlaps with the specified fragment or with a range starting at point<-x to point<-y. Often used in combination with text_buffer<-find to find a fragment overlapping the caret.

fragment ->start: int, move_end=[bool]

Start index (0-based). If move_end equals @off, the end-point is not moved. Otherwise the end-point is moved by the same amount (fragment<-length is not changed).

fragment ->unlink:

Unlinks the fragment from the fragment<-text_buffer and inform the possible related editors of the change.

1.62.3 Get methods

fragment <-end: -> int

The fragment<-end is defined as fragment<-start + fragment<-length. Modifying the fragment<-end modifies the fragment<-length of the fragment.

fragment <-previous: condition=[code] -> fragment

fragment <-next: condition=[code] -> fragment

Return the next/previous fragment of the double linked fragment list for which code succeeds. If code is omitted, these methods return the next/previous fragment of the list. While executing the condition, @arg1 is bound the candidate fragment. Execution may not alter the fragment list of the associated fragment<-text_buffer.

If no fragment can be found in the indicated direction, these methods fail.